Konfiguracija TypeScript: Celovit vodnik po tsconfig.json

TypeScript, nadmnožica JavaScripta, prinaša statično tipizacijo v dinamični svet spletnega razvoja. Dobro nastavljena datoteka tsconfig.json je ključna za izkoriščanje polne moči TypeScripta. Ta vodnik ponuja celovit pregled datoteke tsconfig.json, ki zajema bistvene možnosti prevajalnika, nastavitev projekta in napredne konfiguracije.

Kaj je tsconfig.json?

Datoteka tsconfig.json je konfiguracijska datoteka, ki določa možnosti prevajalnika za projekt TypeScript. Pove prevajalniku TypeScripta, kako naj kodo TypeScript pretvori v JavaScript. Ta datoteka je bistvena za določanje strukture projekta, nastavitev pravil prevajanja in zagotavljanje doslednosti znotraj razvojne ekipe, ne glede na to, ali se ta ekipa nahaja v eni pisarni ali je porazdeljena po več celinah.

Ustvarjanje datoteke tsconfig.json

Za ustvarjanje datoteke tsconfig.json se v terminalu pomaknite v korensko mapo projekta in zaženite naslednji ukaz:

            tsc --init
            

              
                Copy
              
            
          

Ta ukaz ustvari osnovno datoteko tsconfig.json s pogosto uporabljenimi možnostmi prevajalnika. Datoteko lahko nato prilagodite specifičnim zahtevam vašega projekta. Tipična datoteka tsconfig.json bo vključevala možnosti, kot so compilerOptions, include in exclude.

Bistvene možnosti prevajalnika

Odsek compilerOptions je srce datoteke tsconfig.json. Vsebuje širok nabor možnosti, ki nadzorujejo obnašanje prevajalnika TypeScript. Tukaj je nekaj najpomembnejših možnosti prevajalnika:

target

Možnost target določa ciljno različico ECMAScript za generirano kodo JavaScript. Pogoste vrednosti vključujejo ES5, ES6 (ES2015), ES2016, ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ESNext. Izbira pravega cilja je ključna za zagotavljanje združljivosti z namenjenim izvajalskim okoljem, kot so brskalniki ali različice Node.js.

Primer:

            {
  "compilerOptions": {
    "target": "ES2020"
  }
}
            

              
                Copy
              
            
          

module

Možnost module določa slog generiranja kode modulov. Pogoste vrednosti vključujejo CommonJS, AMD, System, UMD, ES6 (ES2015), ES2020 in ESNext. Izbira sistema modulov je odvisna od ciljnega okolja in uporabljenega združevalnika modulov (npr. Webpack, Rollup, Parcel). Za Node.js se pogosto uporablja CommonJS, medtem ko je za sodobne spletne aplikacije prednostna izbira ES6 ali ESNext z združevalnikom modulov. Uporaba ESNext omogoča razvijalcem, da izkoristijo najnovejše funkcije in optimizacije, medtem ko se zanašajo na združevalnik, da poskrbi za končni format modula.

Primer:

            {
  "compilerOptions": {
    "module": "ESNext"
  }
}
            

              
                Copy
              
            
          

lib

Možnost lib določa seznam knjižničnih datotek, ki se vključijo v prevajanje. Te knjižnične datoteke zagotavljajo definicije tipov za vgrajene API-je JavaScripta in API-je brskalnika. Pogoste vrednosti vključujejo ES5, ES6, ES2015, ES2016, ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ESNext, DOM, WebWorker, ScriptHost, ES2015.Core, ES2015.Collection, ES2015.Iterable, ES2015.Promise, ES2015.Proxy, ES2015.Reflect, ES2015.Generator, ES2015.Symbol, ES2015.Symbol.WellKnown, ES2016.Array.Include, ES2017.object, ES2017.Intl, ES2017.SharedMemory, ES2017.String, ES2017.TypedArrays, ES2018.Intl, ES2018.Promise, ES2018.RegExp, ES2019.Array, ES2019.Object, ES2019.String, ES2019.Symbol, ES2020.BigInt, ES2020.Promise, ES2020.String, ES2020.Symbol.WellKnown, ES2021.Promise, ES2021.String, ES2021.WeakRef, ES2022.Error, ES2022.Object, ES2022.String in še veliko več. Izbira ustreznih knjižnic zagotavlja, da ima prevajalnik TypeScript potrebne informacije o tipih za ciljno okolje. Uporaba knjižnice DOM omogoča projektu prevajanje kode, ki uporablja API-je, specifične za brskalnik, brez napak pri tipih.

Primer:

            {
  "compilerOptions": {
    "lib": ["ES2020", "DOM"]
  }
}
            

              
                Copy
              
            
          

allowJs

Možnost allowJs omogoča prevajalniku TypeScript, da prevaja datoteke JavaScript skupaj z datotekami TypeScript. To je uporabno za postopno migracijo obstoječih projektov JavaScript na TypeScript. Nastavitev te možnosti na true omogoči prevajalniku obdelavo datotek .js, kar omogoča postopno uvajanje TypeScripta znotraj projekta.

Primer:

            {
  "compilerOptions": {
    "allowJs": true
  }
}
            

              
                Copy
              
            
          

jsx

Možnost jsx določa, kako naj se obravnava sintaksa JSX. Pogoste vrednosti vključujejo preserve, react, react-native in react-jsx. Vrednost preserve ohrani sintakso JSX v izhodni datoteki, medtem ko react pretvori JSX v klice React.createElement. Vrednost react-jsx uporablja novo transformacijo JSX, uvedeno v React 17, ki ne zahteva uvoza Reacta. Izbira pravilne možnosti JSX je ključna za projekte, ki uporabljajo React ali druge knjižnice, ki temeljijo na JSX.

Primer:

            {
  "compilerOptions": {
    "jsx": "react-jsx"
  }
}
            

              
                Copy
              
            
          

declaration

Možnost declaration ustvari ustrezne deklaracijske datoteke .d.ts za vsako datoteko TypeScript. Deklaracijske datoteke vsebujejo informacije o tipih in jih drugi projekti TypeScript uporabljajo za uporabo prevedene kode. Ustvarjanje deklaracijskih datotek je bistveno za ustvarjanje knjižnic in modulov za večkratno uporabo. Te datoteke omogočajo drugim projektom TypeScript, da razumejo tipe in vmesnike, ki jih knjižnica izpostavlja, ne da bi morali prevajati izvirno izvorno kodo.

Primer:

            {
  "compilerOptions": {
    "declaration": true
  }
}
            

              
                Copy
              
            
          

sourceMap

Možnost sourceMap ustvari datoteke z izvornimi preslikavami (source map files), ki preslikajo generirano kodo JavaScript nazaj na izvirno kodo TypeScript. Izvorne preslikave so bistvene za odpravljanje napak v kodi TypeScript v brskalnikih in drugih okoljih. Ko se v kodi JavaScript pojavi napaka, izvorna preslikava omogoči razvijalcu, da v razhroščevalniku vidi ustrezno kodo TypeScript, kar olajša prepoznavanje in odpravljanje težave.

Primer:

            {
  "compilerOptions": {
    "sourceMap": true
  }
}
            

              
                Copy
              
            
          

outDir

Možnost outDir določa izhodno mapo za generirane datoteke JavaScript. Ta možnost pomaga organizirati izhodne datoteke projekta z ločevanjem izvorne kode od prevedene kode. Uporaba outDir olajša upravljanje procesa gradnje in uvajanje aplikacije.

Primer:

            {
  "compilerOptions": {
    "outDir": "dist"
  }
}
            

              
                Copy
              
            
          

rootDir

Možnost rootDir določa korensko mapo projekta TypeScript. Prevajalnik uporablja to mapo kot osnovo za razreševanje imen modulov. Ta možnost je še posebej pomembna za projekte s kompleksno strukturo map. Pravilna nastavitev rootDir zagotavlja, da lahko prevajalnik najde vse potrebne module in odvisnosti.

Primer:

            {
  "compilerOptions": {
    "rootDir": "src"
  }
}
            

              
                Copy
              
            
          

strict

Možnost strict omogoči vse stroge možnosti preverjanja tipov. To je zelo priporočljivo za nove projekte TypeScript, saj pomaga zgodaj odkriti potencialne napake v razvojnem procesu. Omogočanje strogega načina uveljavlja strožja pravila preverjanja tipov, kar vodi do bolj robustne in vzdržljive kode. Najboljša praksa je, da se strogi način omogoči v vseh novih projektih TypeScript.

Primer:

            {
  "compilerOptions": {
    "strict": true
  }
}
            

              
                Copy
              
            
          

esModuleInterop

Možnost esModuleInterop omogoča interoperabilnost med moduli CommonJS in ES. To je pomembno za projekte, ki uporabljajo obe vrsti modulov. Ko je esModuleInterop omogočen, bo TypeScript samodejno obravnaval razlike med moduli CommonJS in ES, kar olajša uvažanje in izvažanje modulov med obema sistemoma. Ta možnost je še posebej uporabna pri delu s knjižnicami tretjih oseb, ki morda uporabljajo različne sisteme modulov.

Primer:

            {
  "compilerOptions": {
    "esModuleInterop": true
  }
}
            

              
                Copy
              
            
          

moduleResolution

Možnost moduleResolution določa, kako TypeScript razrešuje uvoze modulov. Pogosti vrednosti sta Node in Classic. Strategija razreševanja modulov Node je privzeta in temelji na algoritmu za razreševanje modulov v Node.js. Strategija razreševanja modulov Classic je starejša in se manj pogosto uporablja. Uporaba strategije razreševanja modulov Node zagotavlja, da lahko TypeScript pravilno razreši uvoze modulov v okolju Node.js.

Primer:

            {
  "compilerOptions": {
    "moduleResolution": "Node"
  }
}
            

              
                Copy
              
            
          

baseUrl in paths

Možnosti baseUrl in paths se uporabljata za konfiguracijo razreševanja modulov za ne-relativne uvoze modulov. Možnost baseUrl določa osnovno mapo za razreševanje ne-relativnih imen modulov. Možnost paths vam omogoča preslikavo imen modulov na določene lokacije v datotečnem sistemu. Ti možnosti sta še posebej uporabni za projekte s kompleksno strukturo map in za poenostavitev uvoza modulov. Uporaba baseUrl in paths lahko naredi kodo bolj berljivo in vzdržljivo.

Primer:

            {
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@components/*": ["src/components/*"],
      "@utils/*": ["src/utils/*"]
    }
  }
}
            

              
                Copy
              
            
          

Možnosti Include in Exclude

Možnosti include in exclude določata, katere datoteke naj se vključijo v prevajanje in katere datoteke naj se izključijo. Te možnosti uporabljajo glob vzorce za ujemanje imen datotek. Uporaba include in exclude vam omogoča nadzor nad tem, katere datoteke obdeluje prevajalnik TypeScript, kar izboljša zmogljivost gradnje in zmanjša število napak. Najboljša praksa je, da se datoteke, ki jih je treba vključiti v prevajanje, eksplicitno določijo.

Primer:

            {
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
            

              
                Copy
              
            
          

Možnost Extends

Možnost extends vam omogoča, da podedujete možnosti prevajalnika iz druge datoteke tsconfig.json. To je uporabno za deljenje skupnih nastavitev konfiguracije med več projekti ali za ustvarjanje osnovnih konfiguracij. Uporaba možnosti extends spodbuja ponovno uporabo kode in zmanjšuje podvajanje. Najboljša praksa je ustvariti osnovne konfiguracije in jih razširiti v posameznih projektih.

Primer:

            {
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "jsx": "react-jsx"
  },
  "include": ["src/**/*"]
}
            

              
                Copy
              
            
          

Napredne konfiguracije

Poleg bistvenih možnosti prevajalnika tsconfig.json podpira tudi napredne konfiguracije za specializirane scenarije.

Inkrementalno prevajanje

Pri velikih projektih lahko inkrementalno prevajanje znatno izboljša čas gradnje. TypeScript lahko predpomni rezultate prejšnjih prevajanj in ponovno prevede samo datoteke, ki so se spremenile. Omogočanje inkrementalnega prevajanja lahko dramatično skrajša čas gradnje za velike projekte. To je še posebej pomembno za projekte z velikim številom datotek in odvisnosti.

            {
  "compilerOptions": {
    "incremental": true,
    "tsBuildInfoFile": ".tsbuildinfo"
  }
}
            

              
                Copy
              
            
          

Reference projektov

Reference projektov vam omogočajo, da velike projekte TypeScript strukturirate v manjše, neodvisne module. To lahko izboljša čas gradnje in organizacijo kode. Uporaba referenc projektov lahko naredi velike projekte bolj obvladljive in lažje za vzdrževanje. Najboljša praksa je uporaba referenc projektov za velike, kompleksne projekte.

            {
  "compilerOptions": {
    "composite": true
  },
  "references": [
    { "path": "./module1" },
    { "path": "./module2" }
  ]
}
            

              
                Copy
              
            
          

Definicije tipov po meri

Včasih boste morda morali zagotoviti definicije tipov za knjižnice JavaScript, ki jih nimajo. Ustvarite lahko datoteke .d.ts po meri, da definirate tipe za te knjižnice. Ustvarjanje definicij tipov po meri vam omogoča uporabo knjižnic JavaScript v vaši kodi TypeScript, ne da bi pri tem žrtvovali varnost tipov. To je še posebej uporabno pri delu z zastarelo kodo JavaScript ali knjižnicami, ki ne zagotavljajo lastnih definicij tipov.

            // custom.d.ts
declare module 'my-library' {
  export function doSomething(x: number): string;
}
            

              
                Copy
              
            
          

Najboljše prakse

• Uporabite strogi način: Omogočite možnost strict za izboljšano preverjanje tipov.
• Določite cilj: Izberite ustrezno različico target za vaše izvajalsko okolje.
• Organizirajte izhodne datoteke: Uporabite outDir za ločevanje izvorne kode od prevedene kode.
• Upravljajte odvisnosti: Uporabite include in exclude za nadzor nad tem, katere datoteke se prevajajo.
• Izkoristite Extends: Delite skupne nastavitve konfiguracije z možnostjo extends.
• Shranjujte konfiguracijo v sistem za nadzor različic: Shranite tsconfig.json v git za ohranjanje doslednosti med razvojnimi okolji in cevovodi CI/CD.

Odpravljanje pogostih težav

Konfiguriranje datoteke tsconfig.json je lahko včasih izziv. Tukaj je nekaj pogostih težav in njihovih rešitev:

Težave z razreševanjem modulov

Če naletite na napake pri razreševanju modulov, se prepričajte, da je možnost moduleResolution pravilno nastavljena in da sta možnosti baseUrl in paths pravilno nastavljeni. Dvakrat preverite poti, določene v možnosti paths, da se prepričate, da so pravilne. Preverite, ali so vsi potrebni moduli nameščeni v mapi node_modules.

Napake pri tipih

Napake pri tipih se lahko pojavijo, če so definicije tipov napačne ali manjkajo. Prepričajte se, da imate nameščene pravilne definicije tipov za vse knjižnice, ki jih uporabljate. Če uporabljate knjižnico JavaScript, ki nima definicij tipov, razmislite o ustvarjanju definicij tipov po meri.

Napake pri prevajanju

Napake pri prevajanju se lahko pojavijo, če so v vaši kodi TypeScript sintaktične napake ali napake pri tipih. Pazljivo preglejte sporočila o napakah in popravite morebitne sintaktične napake ali napake pri tipih. Prepričajte se, da vaša koda sledi konvencijam kodiranja TypeScript.

Zaključek

Dobro nastavljena datoteka tsconfig.json je bistvena za uspešen projekt TypeScript. Z razumevanjem bistvenih možnosti prevajalnika in naprednih konfiguracij lahko optimizirate svoj razvojni potek dela, izboljšate kakovost kode in zagotovite združljivost s ciljnim okoljem. Vlaganje časa v pravilno konfiguracijo tsconfig.json se bo dolgoročno obrestovalo z zmanjšanjem napak, izboljšanjem vzdržljivosti in poenostavitvijo procesa gradnje. To vodi k bolj učinkovitemu in zanesljivemu razvoju programske opreme. Informacije, podane tukaj, so zasnovane tako, da so univerzalno uporabne in bi morale zagotoviti trdne temelje za začetek novega projekta s TypeScriptom.

Ne pozabite se posvetovati z uradno dokumentacijo TypeScript za najnovejše informacije in podrobna pojasnila vseh razpoložljivih možnosti prevajalnika. Dokumentacija TypeScript je dragocen vir za razumevanje podrobnosti konfiguracije TypeScripta.